Gelişmiş derleyici seçeneklerini ve en iyi uygulamaları kapsayan, optimum TypeScript geliştirme için tsconfig.json dosyasını anlama ve yapılandırma konusunda kapsamlı bir rehber.
TypeScript Yapılandırması: TSConfig Derleyici Seçeneklerinde Uzmanlaşmak
tsconfig.json dosyası, herhangi bir TypeScript projesinin kalbidir. TypeScript derleyicisinin (tsc) .ts dosyalarınızı JavaScript'e nasıl dönüştüreceğini belirler. İyi yapılandırılmış bir tsconfig.json, kod kalitesini korumak, farklı ortamlarda uyumluluğu sağlamak ve derleme sürecini optimize etmek için çok önemlidir. Bu kapsamlı rehber, gelişmiş tsconfig.json seçeneklerine derinlemesine dalmakta ve TypeScript projelerinizi en yüksek performans ve sürdürülebilirlik için ince ayar yapmanızı sağlamaktadır.
Temelleri Anlamak: TSConfig Neden Önemlidir?
Gelişmiş seçeneklere geçmeden önce, tsconfig.json'un neden bu kadar önemli olduğunu özetleyelim:
- Derleme Kontrolü: Projenize hangi dosyaların dahil edilmesi gerektiğini ve bunların nasıl derlenmesi gerektiğini belirtir.
- Tip Kontrolü: Tip kontrolünün kurallarını ve titizliğini tanımlayarak, geliştirme döngüsünün başlarında hataları yakalamanıza yardımcı olur.
- Çıktı Kontrolü: Hedef JavaScript sürümünü, modül sistemini ve çıktı dizinini belirler.
- IDE Entegrasyonu: Kod tamamlama, hata vurgulama ve yeniden düzenleme gibi özellikler için IDE'lere (VS Code, WebStorm vb. gibi) değerli bilgiler sağlar.
Bir tsconfig.json dosyası olmadan, TypeScript derleyicisi, tüm projeler için uygun olmayabilecek varsayılan ayarları kullanacaktır. Bu, beklenmedik davranışlara, uyumluluk sorunlarına ve idealden daha az bir geliştirme deneyimine yol açabilir.
TSConfig'unuzu Oluşturma: Hızlı Başlangıç
Bir tsconfig.json dosyası oluşturmak için, projenizin kök dizininde aşağıdaki komutu çalıştırmanız yeterlidir:
tsc --init
Bu, bazı yaygın seçeneklerle temel bir tsconfig.json dosyası oluşturacaktır. Daha sonra bu dosyayı projenizin özel gereksinimlerini karşılayacak şekilde özelleştirebilirsiniz.
Temel Derleyici Seçenekleri: Ayrıntılı Bir Bakış
tsconfig.json dosyası, TypeScript derleyicisini yapılandırdığınız compilerOptions nesnesini içerir. En önemli ve yaygın olarak kullanılan seçeneklerden bazılarını inceleyelim:
target
Bu seçenek, derlenen JavaScript kodu için ECMAScript hedef sürümünü belirtir. Derleyicinin kullanacağı JavaScript özelliklerini belirleyerek, hedef ortamla (örneğin, tarayıcılar, Node.js) uyumluluğu sağlar. Yaygın değerler arasında ES5, ES6 (ES2015), ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext bulunur. ESNext kullanmak, en son desteklenen ECMAScript özelliklerini hedefleyecektir.
Örnek:
"compilerOptions": {
"target": "ES2020"
}
Bu yapılandırma, derleyiciye ECMAScript 2020 ile uyumlu JavaScript kodu oluşturmasını emredecektir.
module
Bu seçenek, derlenen JavaScript kodunda kullanılacak modül sistemini belirtir. Yaygın değerler arasında CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 ve ESNext bulunur. Modül sistemi seçimi, hedef ortama ve kullanılan modül yükleyiciye (örneğin, Node.js, Webpack, Browserify) bağlıdır.
Örnek:
"compilerOptions": {
"module": "CommonJS"
}
Bu yapılandırma, genellikle CommonJS modül sistemini kullanan Node.js projeleri için uygundur.
lib
Bu seçenek, derleme işlemine dahil edilecek kitaplık dosyası kümesini belirtir. Bu kitaplık dosyaları, yerleşik JavaScript API'leri ve tarayıcı API'leri için tür tanımlamaları sağlar. Yaygın değerler arasında ES5, ES6, ES7, DOM, WebWorker, ScriptHost ve daha fazlası bulunur.
Örnek:
"compilerOptions": {
"lib": ["ES2020", "DOM"]
}
Bu yapılandırma, ECMAScript 2020 ve DOM API'si için tür tanımlamalarını içerir, bu da tarayıcı tabanlı projeler için gereklidir.
allowJs
Bu seçenek, TypeScript derleyicisinin TypeScript dosyalarıyla birlikte JavaScript dosyalarını derlemesine izin verir. Bu, bir JavaScript projesini TypeScript'e geçirirken veya mevcut JavaScript kod tabanlarıyla çalışırken kullanışlı olabilir.
Örnek:
"compilerOptions": {
"allowJs": true
}
Bu seçenek etkinleştirildiğinde, derleyici hem .ts hem de .js dosyalarını işleyecektir.
checkJs
Bu seçenek, JavaScript dosyaları için tip kontrolünü etkinleştirir. allowJs ile birleştirildiğinde, TypeScript'in JavaScript kodunuzdaki potansiyel tip hatalarını belirlemesini sağlar.
Örnek:
"compilerOptions": {
"allowJs": true,
"checkJs": true
}
Bu yapılandırma, hem TypeScript hem de JavaScript dosyaları için tip kontrolü sağlar.
jsx
Bu seçenek, JSX sözdiziminin (React ve diğer çerçevelerde kullanılır) nasıl dönüştürülmesi gerektiğini belirtir. Yaygın değerler arasında preserve, react, react-native ve react-jsx bulunur. preserve JSX sözdizimini olduğu gibi bırakır, react onu React.createElement çağrılarına dönüştürür, react-native React Native geliştirmesi içindir ve react-jsx onu JSX fabrika fonksiyonlarına dönüştürür. react-jsxdev geliştirme amaçlıdır.
Örnek:
"compilerOptions": {
"jsx": "react"
}
Bu yapılandırma, JSX'i React.createElement çağrılarına dönüştüren React projeleri için uygundur.
declaration
Bu seçenek, TypeScript kodunuz için bildirim dosyaları (.d.ts) oluşturur. Bildirim dosyaları, kodunuz için tür bilgisi sağlar ve diğer TypeScript projelerinin veya JavaScript projelerinin, kodunuzu uygun tip kontrolü ile kullanmasına izin verir.
Örnek:
"compilerOptions": {
"declaration": true
}
Bu yapılandırma, derlenen JavaScript dosyalarıyla birlikte .d.ts dosyaları oluşturacaktır.
declarationMap
Bu seçenek, oluşturulan bildirim dosyaları için kaynak harita dosyaları (.d.ts.map) oluşturur. Kaynak haritalar, hata ayıklayıcıların ve diğer araçların, bildirim dosyalarıyla çalışırken orijinal TypeScript kaynak koduna geri eşlenmesini sağlar.
Örnek:
"compilerOptions": {
"declaration": true,
"declarationMap": true
}
sourceMap
Bu seçenek, derlenen JavaScript kodu için kaynak harita dosyaları (.js.map) oluşturur. Kaynak haritalar, hata ayıklayıcıların ve diğer araçların, tarayıcıda veya diğer ortamlarda hata ayıklama yaparken orijinal TypeScript kaynak koduna geri eşlenmesini sağlar.
Örnek:
"compilerOptions": {
"sourceMap": true
}
outFile
Bu seçenek, tüm çıktı dosyalarını tek bir dosyada birleştirir ve yayar. Bu genellikle tarayıcı tabanlı uygulamalar için kodu paketlemek için kullanılır.
Örnek:
"compilerOptions": {
"outFile": "dist/bundle.js"
}
outDir
Bu seçenek, derlenen JavaScript dosyaları için çıktı dizinini belirtir. Belirtilmezse, derleyici çıktı dosyalarını kaynak dosyalarla aynı dizine yerleştirir.
Örnek:
"compilerOptions": {
"outDir": "dist"
}
Bu yapılandırma, derlenen JavaScript dosyalarını dist dizinine yerleştirecektir.
rootDir
Bu seçenek, TypeScript projesinin kök dizinini belirtir. Derleyici, modül adlarını çözümlemek ve çıktı dosya yollarını oluşturmak için bu dizini kullanır. Bu, özellikle karmaşık proje yapıları için kullanışlıdır.
Örnek:
"compilerOptions": {
"rootDir": "src"
}
removeComments
Bu seçenek, derlenen JavaScript kodundan yorumları kaldırır. Bu, çıktı dosyalarının boyutunu küçültmeye yardımcı olabilir.
Örnek:
"compilerOptions": {
"removeComments": true
}
noEmitOnError
Bu seçenek, herhangi bir tip hatası tespit edilirse derleyicinin JavaScript dosyaları yaymasını engeller. Bu, yalnızca geçerli kodun oluşturulmasını sağlar.
Örnek:
"compilerOptions": {
"noEmitOnError": true
}
strict
Bu seçenek, tüm katı tip kontrolü seçeneklerini etkinleştirir. Bu, potansiyel hataları yakalamaya ve en iyi uygulamaları uygulamaya yardımcı olduğundan, yeni projeler için şiddetle tavsiye edilir.
Örnek:
"compilerOptions": {
"strict": true
}
Katı modu etkinleştirmek, aşağıdaki seçenekleri etkinleştirmeye eşdeğerdir:
noImplicitAnynoImplicitThisalwaysStrictstrictNullChecksstrictFunctionTypesstrictBindCallApplynoImplicitReturnsnoFallthroughCasesInSwitch
esModuleInterop
Bu seçenek, CommonJS ve ES modülleri arasında birlikte çalışabilirliği etkinleştirir. CommonJS modüllerini ES modüllerinde ve tersini içe aktarmanıza izin verir.
Örnek:
"compilerOptions": {
"esModuleInterop": true
}
forceConsistentCasingInFileNames
Bu seçenek, dosya adlarında tutarlı büyük/küçük harf kullanımını zorlar. Bu, bazı işletim sistemlerinin büyük/küçük harfe duyarlı olması ve bazılarının olmaması nedeniyle platformlar arası uyumluluk için önemlidir.
Örnek:
"compilerOptions": {
"forceConsistentCasingInFileNames": true
}
baseUrl ve paths
Bu seçenekler, modül çözümlemesini yapılandırmanıza olanak tanır. baseUrl, göreli olmayan modül adlarını çözümlemek için temel dizini belirtir ve paths özel modül takma adları tanımlamanıza olanak tanır.
Örnek:
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@components/*": ["src/components/*"],
"@utils/*": ["src/utils/*"]
}
}
Bu yapılandırma, @components/MyComponent ve @utils/myFunction gibi takma adlar kullanarak modülleri içe aktarmanıza olanak tanır.
Gelişmiş Yapılandırma: Temellerin Ötesinde
Şimdi, TypeScript geliştirme deneyiminizi daha da geliştirebilecek bazı gelişmiş tsconfig.json seçeneklerini inceleyelim.
Artımlı Derleme
TypeScript, büyük projeler için derleme sürecini önemli ölçüde hızlandırabilen artımlı derlemeyi destekler. Artımlı derlemeyi etkinleştirmek için, incremental seçeneğini true olarak ayarlayın ve bir tsBuildInfoFile seçeneği belirtin.
Örnek:
"compilerOptions": {
"incremental": true,
"tsBuildInfoFile": ".tsbuildinfo"
}
tsBuildInfoFile seçeneği, derleyicinin derleme bilgilerini saklayacağı dosyayı belirtir. Bu bilgi, sonraki derlemeler sırasında hangi dosyaların yeniden derlenmesi gerektiğini belirlemek için kullanılır.
Proje Referansları
Proje referansları, kodunuzu daha küçük, daha yönetilebilir projelere yapılandırmanıza olanak tanır. Bu, büyük kod tabanları için derleme sürelerini ve kod organizasyonunu iyileştirebilir. Bu konsepte iyi bir benzetme, bir Mikro hizmet mimarisidir - her hizmet bağımsızdır, ancak ekosistemdeki diğerlerine bağlıdır.
Proje referanslarını kullanmak için, her proje için ayrı bir tsconfig.json dosyası oluşturmanız gerekir. Daha sonra, ana tsconfig.json dosyasında, references seçeneğini kullanarak başvurulması gereken projeleri belirtebilirsiniz.
Örnek:
{
"compilerOptions": {
...
},
"references": [
{ "path": "./project1" },
{ "path": "./project2" }
]
}
Bu yapılandırma, geçerli projenin ./project1 ve ./project2 dizinlerinde bulunan projelere bağlı olduğunu belirtir.
Özel Dönüştürücüler
Özel dönüştürücüler, TypeScript derleyicisinin çıktısını değiştirmenize olanak tanır. Bu, özel kod dönüşümleri eklemek, kullanılmayan kodu kaldırmak veya belirli ortamlar için çıktıyı optimize etmek gibi çeşitli amaçlar için kullanılabilir. Genellikle i18n uluslararasılaştırma ve yerelleştirme görevleri için kullanılırlar.
Özel dönüştürücüleri kullanmak için, derleyici tarafından çağrılacak bir işlevi dışa aktaran ayrı bir JavaScript dosyası oluşturmanız gerekir. Daha sonra, tsconfig.json dosyasındaki plugins seçeneğini kullanarak dönüştürücü dosyasını belirleyebilirsiniz.
Örnek:
{
"compilerOptions": {
...
"plugins": [
{ "transform": "./transformer.js" }
]
}
}
Bu yapılandırma, ./transformer.js dosyasının özel bir dönüştürücü olarak kullanılması gerektiğini belirtir.
Dosyalar, Dahil Etme ve Hariç Tutma
compilerOptions'ın ötesinde, tsconfig.json'daki diğer kök düzey seçenekler, derleme sürecine hangi dosyaların dahil edildiğini kontrol eder:
- files: Derlemeye dahil edilecek dosya yollarının dizisi.
- include: Dahil edilecek dosyaları belirten glob desenlerinin dizisi.
- exclude: Hariç tutulacak dosyaları belirten glob desenlerinin dizisi.
Bu seçenekler, TypeScript derleyicisi tarafından hangi dosyaların işlendiği konusunda ayrıntılı kontrol sağlar. Örneğin, derleme işleminden test dosyalarını veya oluşturulan kodu hariç tutabilirsiniz.
Örnek:
{
"compilerOptions": { ... },
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
Bu yapılandırma, src dizinindeki ve alt dizinlerindeki tüm dosyaları dahil ederken, node_modules ve dist dizinlerindeki dosyaları ve .spec.ts uzantısına sahip (genellikle birim testleri için kullanılan) herhangi bir dosyayı hariç tutar.
Belirli Senaryolar İçin Derleyici Seçenekleri
Farklı projeler, optimum sonuçlar elde etmek için farklı derleyici ayarları gerektirebilir. Şimdi, birkaç özel senaryoya ve her biri için önerilen derleyici ayarlarına bakalım.
Web Uygulaması Geliştirme
Web uygulaması geliştirme için, genellikle aşağıdaki derleyici ayarlarını kullanmak istersiniz:
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "Node",
"jsx": "react-jsx",
"esModuleInterop": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"sourceMap": true,
"outDir": "dist"
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
Bu ayarlar, React veya diğer benzer çerçeveleri kullanan modern web uygulamaları için uygundur. En son ECMAScript özelliklerini hedefler, ES modüllerini kullanır ve katı tip kontrolünü etkinleştirirler.
Node.js Arka Uç Geliştirme
Node.js arka uç geliştirmesi için, genellikle aşağıdaki derleyici ayarlarını kullanmak istersiniz:
{
"compilerOptions": {
"target": "ESNext",
"module": "CommonJS",
"esModuleInterop": true,
"strict": true,
"sourceMap": true,
"outDir": "dist",
"resolveJsonModule": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
Bu ayarlar, CommonJS modül sistemini kullanan Node.js uygulamaları için uygundur. En son ECMAScript özelliklerini hedefler, katı tip kontrolünü etkinleştirir ve JSON dosyalarını modül olarak içe aktarmanıza izin verir.
Kitaplık Geliştirme
Kitaplık geliştirme için, genellikle aşağıdaki derleyici ayarlarını kullanmak istersiniz:
{
"compilerOptions": {
"target": "ES5",
"module": "UMD",
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"outDir": "dist",
"strict": true,
"esModuleInterop": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "**/*.spec.ts"]
}
Bu ayarlar, hem tarayıcı hem de Node.js ortamlarında kullanılabilen kitaplıklar oluşturmak için uygundur. Geliştirici deneyimini iyileştirmek için bildirim dosyaları ve kaynak haritaları oluştururlar.
TSConfig Yönetimi İçin En İyi Uygulamalar
tsconfig.json dosyalarınızı yönetirken aklınızda bulundurmanız gereken bazı en iyi uygulamalar şunlardır:
- Temel bir yapılandırmayla başlayın: Ortak ayarlara sahip temel bir
tsconfig.jsondosyası oluşturun ve ardındanextendsseçeneğini kullanarak diğer projelerde genişletin. - Katı modu kullanın: Potansiyel hataları yakalamak ve en iyi uygulamaları uygulamak için katı modu etkinleştirin.
- Modül çözümlemesini yapılandırın: İçe aktarma hatalarını önlemek için modül çözümlemesini düzgün bir şekilde yapılandırın.
- Proje referanslarını kullanın: Kodunuzu proje referanslarını kullanarak daha küçük, daha yönetilebilir projelere yapılandırın.
tsconfig.jsondosyanızı güncel tutun:tsconfig.jsondosyanızı düzenli olarak gözden geçirin ve projeniz geliştikçe güncelleyin.tsconfig.jsondosyanızı sürüm kontrolü yapın:tsconfig.jsondosyanızı diğer kaynak kodunuzla birlikte sürüm kontrolüne kaydedin.- Yapılandırmanızı belgeleyin: Her seçeneğin amacını açıklamak için
tsconfig.jsondosyanıza yorumlar ekleyin.
Sonuç: TypeScript Yapılandırmasında Uzmanlaşmak
tsconfig.json dosyası, TypeScript derleyicisini yapılandırmak ve derleme sürecini kontrol etmek için güçlü bir araçtır. Mevcut seçenekleri anlayarak ve en iyi uygulamaları izleyerek, TypeScript projelerinizi optimum performans, sürdürülebilirlik ve uyumluluk için ince ayar yapabilirsiniz. Bu rehber, tsconfig.json dosyasında bulunan gelişmiş seçeneklerin kapsamlı bir genel bakışını sunarak, TypeScript geliştirme iş akışınızın tam kontrolünü elinize almanızı sağlar. En güncel bilgiler ve rehberlik için her zaman resmi TypeScript belgelerine başvurun. Projeleriniz geliştikçe, bu güçlü yapılandırma araçlarını anlama ve kullanma biçiminiz de gelişmelidir. İyi kodlamalar!